BScreen

Derived from: none

Declared in: be/interface/Screen.h

Library: libbe.so

Allocation: Constructor or on the stack

Summary

A BScreen object represents a single display screen that's connected to the computer. With a BScreen object you can...

• Get and set the screen's size and pixel depth.

• Get the screen's color map.

• Make a screen shot.

• Set the desktop color.

• Synchronize your code with the screen's retrace event.

You can't copy a BScreen object—the copy constructor and assignment operators are private.

Multiple Screens

Although, the BeOS currently only supports a single screen, in the future it will let the user hook up multiple screens. One of the screens, the main screen, will have the origin of the screen coordinate system at its left top corner. Other screens will be located elsewhere in the same coordinate system. If there's just one screen, it's the main screen.

A BScreen object represents one screen. An application can have more than one object referring to the same screen.

When multiple screens are supported, a screen_id identifier will be assigned to each one. Currently, B_MAIN_SCREEN_ID is the only identifier.

Constructor and Destructor

BScreen()

	BScreen(BWindow *window) BScreen(screen_id id = B_MAIN_SCREEN_ID)

Initializes the BScreen object so that it represents the screen where window is displayed or the screen identified by id. If window is NULL or hidden, or if the id is invalid, the BScreen will represent the main screen.

Since multiple monitors aren't currently supported, there's no API for screen identifiers other than for the main screen.

To be sure the new object was correctly constructed, call IsValid().

~BScreen()

	~BScreen()

Unlocks the screen and invalidates the BScreen object.

Member Functions

ColorForIndex() see ColorMap()

ColorMap() , IndexForColor() , ColorForIndex()

	const color_map *ColorMap(void) inline uint8 IndexForColor(rgb_color color) uint8 IndexForColor(uint8 red, uint8 green, uint8 blue, uint8 alpha = 255) rgb_color ColorForIndex(const uint8 index) uint8 InvertIndex(uint8 index)

These functions return information from the color_map structure for this screen. The color_map structure defines the set of 256 colors that can be displayed in an B_CMAP8 color space. A single color_map is shared by all applications that display on the same screen. See the color_map structure for more information about the structure.

ColorMap() returns a pointer to the color_map itself. The structure belongs to the BScreen object; you can't modify or free it. (Note that the the system_colors() function retrieves the color_map structure for the main screen without reference to a BScreen object.)

IndexForColor() returns the "index" of the 8-bit color that, in this screen's color map, most closely matches the given 32-bit color. You can pass the index to functions such BBitmap::SetBits() to set an 8-bit color. Note that IndexForColor() knows how to convert B_TRANSPARENT_32_BIT into B_TRANSPARENT_8_BIT.

ColorForIndex() returns the 32-bit color representation of a given 8-bit color index. This function doesn't convert B_TRANSPARENT_8_BIT into B_TRANSPARENT_32_BIT.

InvertIndex() takes an 8-bit index and returns an index that represents the color's "inversion." Inverted colors are typically used for highlighting.

The information gained through IndexForColor(), ColorForIndex(), and InvertIndex() can be retrieved more efficiently from the color_map structure. If you're repeatedly calling these functions, you should consider accessing the color_map structure, instead. Note, however, that the intelligent B_TRANSPARENT_32_BIT to B_TRANSPARENT_8_BIT conversion is not supported by the structure.

ColorSpace()

	color_space ColorSpace(void)

Returns the color space of the screen display—typically B_CMAP8, B_RGB15, or B_RGB32—or B_NO_COLOR_SPACE if the BScreen object is invalid.

The color space is set by the user through the Screen preferences application. You can set it programatically through the SetMode() function.

DesktopColor() see SetDesktopColor()

DPMSCapabilities() see SetDPMS()

DPMSState() see SetDPMS()

Frame()

	BRect Frame(void)

Returns the rectangle that locates the screen in the screen coordinate system. For example, the frame for a 1,024 * 768 main screen looks like this:

   BRect(0.0, 0.0, 1023.0, 767.0)

If the BScreen object is invalid, all sides of the rectangle are set to 0.0.

The screen's frame rectangle is set by the user through the Screen preferences application. You can set it programatically through the SetMode() function.

GetBitmap() see ReadBitmap()

GetDeviceInfo

	status_t GetDeviceInfo(accelerant_device_info *info)

Returns information about the graphics card.

GetMode() see GetModeList()

GetModeList() , SetMode() , GetMode()

	status_t GetModeList(display_mode **mode_list, uint32 *count) status_t SetMode(display_mode *mode, bool makeDefault = false) status_t GetMode(display_mode *mode)

These functions set and get the screen's display mode. Each display_mode structure (defined in add-ons/graphics/Accelerant.h) is a distinct combination of screen size, pixel depth, and display timing.

GetModeList() allocates and returns, in mode_list, a list of the display_mode structures that the graphics card is guaranteed to support; count is set to the number of display_mode elements in the list. The caller is responsible for freeing mode_list.

There's no guarantee that the monitor can support all of the modes that GetModeList() retrieves.

SetMode() resets the screen to the given mode. If makeDefault is true, the mode becomes the default for the current workspace.

GetMode() copies the current display_mode into mode.

The display_mode structure is:

	typedef struct {       display_timing timing;       uint32 space;       uint16 virtual_width;       uint16 virtual_height;       uint16 h_display_start;       uint16 v_display_start;       uint32 flags;       } display_mode;

• timing provides CTRC timing information.

• space is the color space of the display.

• virtual_width is the screen's virtual width in pixels, and virtual_height is the screen's virtual height in lines.

• h_display_start is the first displayed pixel in a line, and v_display_start is the first displayeed line.

• flags are mode flags:

Constant	Meaning
B_SCROLL	Scrolling display; a large display is being simulated by scrolling around on a smaller screen.
B_8_BIT_DAC	The DAC is in 8-bit mode.
B_HARDWARE_CURSOR	The mode supports a hardware cursor.
B_PARALLEL_ACCESS	The mode supports parallel access.
B_DPMS	The mode supports power management.
B_IO_FB_NA	The graphics card's frame buffer shouldn't be touched by the Application Server while the card's acceleration engine might be doing so.

The display_timing structure is:

	typedef struct {       uint32 pixel_clock;       uint16 h_display;       uint16 h_sync_start;       uint16 h_sync_end;       uint16 h_total;       uint16 v_display;       uint16 h_display;       uint16 v_sync_start;       uint16 v_sync_end;       uint16 v_total;       uint32 flags;       } display_timing;

• pixel_clock is in kHz.

• h_display is in pixels, not in character clocks.

• v_display is in lines.

• flags are:

Constant	Meaning
B_BLANK_PEDESTAL	Use a 7.5 IRE blanking pedestal instead of a 0.0 IRE blanking pedestal. Usually 0.0 IRE.
B_TIMING_INTERLACED	The mode is interlaced instead of progressively scanned. Rarely set; most modern displays don't need this.
B_POSITIVE_HSYNC	If set, the mode uses a positive (high) sync polarity.
B_POSITIVE_VSYNC	If set, the mode uses a negative (low) sync polarity.
B_SYNC_ON_GREEN	The mode generates sync information on the green color signal.

See also: ProposeMode()

GetPixelClockLimits()

	status_t GetPixelClockLimits(display_mode *mode,       uint32 *low,       uint32 *high)

This function returns, in low and high, the minimum and maximum "pixel clock" rates (in thousands-of-pixels per second) that are possible for the given mode. Given the pixel clock and a display mode, you can determine the refresh rate range by dividing the pixel clock by the "real" size of the screen, thus:

   uint32 hi_clock, lo_clock;
   float hi_refresh, lo_refresh;
   float real_size;
   display_mode mode;
   GetMode(&mode);
   GetPixelClockLimits(&mode, &lo_clock, &hi_clock);
   
   /* The real screen dimensions (i.e. the dimensions for the purposes
    * of the gun) are given by the >timing.h_total> and 
    * >timing.v_total> fields.
    */
   total_size = mode.timing.h_total * mode.timing.v_total
   
   /* Get the refresh rate by dividing the pixel clock by the total
    * screen size.  Remember -- the pixel clock values are given in
    * kHz; we multiply by 1000.0 to retrieve refresh rates in Hz.
    */ 
   hi_refresh = ((float)hi_clock*1000.0)/(float)total_size;
   lo_refresh = ((float)lo_clock*1000.0)/(float)total_size;

RETURN CODES

• B_OK. Pixel clock limits returned successfully.

• B_ERROR. No clock limits known.

GetTimingConstraints()

	status_t GetTimingConstraints(display_timing_constraints *dtc)

This function fills out the dtc structure with the timing constraints of the current display mode.

RETURN CODES

• B_OK. Constraints returned successfully.

• B_ERROR. No constraints known.

ID()

	screen_id ID(void)

Returns the identifier for the screen. The main screen is identified as B_MAIN_SCREEN_ID.

The ID isn't presistent across boots, and may change if the monitor is diconnected and then reconnected.

Currently, this function always returns B_MAIN_SCREEN_ID, even if the BScreen object is invalid.

IndexForColor() see ColorMap()

InvertIndex() see ColorMap()

IsValid()

	bool IsValid(void)

Returns true if the BScreen object is valid (if it represents a real screen connected to the computer), and false if not.

ProposeMode()

	status_t ProposeMode(display_mode *candidate,       const display_mode *low,       const display_mode *high)

ProposeMode() is a convenience function that attempts to adjust candidate so that it's a supported mode (as listed by the GetModeList() function). It then compares the possibly-adjusted candidate to the limits declared in low and high and expresses this comparison in the return value. Note that the function doesn't adjust candidate so that it is, of necessity, between low and high.

Exactly how ProposeMode() works is up to the individual graphics driver. It's expected that the function will adjust candidate's screen size fields while holding the color space constant.

This function was formerly called ProposeDisplayMode().

RETURN CODES

• B_OK. candidate (as returned) is supported and falls within the limits.

• B_BAD_VALUE. candidate (as returned) is supported, but doesn't fall within the limits.

• B_ERROR. candidate isn't supported.

See also: GetModeList()

ReadBitmap() , GetBitmap()

	status_t ReadBitmap(BBitmap *buffer,       bool draw_cursor = true,       BRect *bounds = NULL) status_t GetBitmap(BBitmap **buffer,       bool draw_cursor = true,       BRect *bounds = NULL)

These functions provide read-only access to the screen by copying the screen's contents into the first argument BBitmap. The difference between them is that ReadBitmap() expects you to allocate the BBitmap before passing it in, while GetBitmap() allocates a new BBitmap for you. The caller is responsible for freeing the BBitmap allocated by GetBitmap().

The draw_cursor argument determines whether the cursor is drawn in the screen shot; bounds let you specify the region, in screen coordinates, that you want copied. If bounds is NULL, the entire screen is copied. The functions fail if the bounds rectangle doesn't fall wholly within the screen's frame.

The functions return B_OK on success or B_ERROR on failure.

SetDesktopColor() , DesktopColor()

	void SetDesktopColor(rgb_color color, bool makeDefault = true) rgb_color DesktopColor(void)

These functions set and return the color of the desktop—the backdrop against which windows are displayed on the screen. SetDesktopColor() makes an immediate change in the desktop color displayed on-screen; DesktopColor() returns the color currently displayed.

If the makeDefault flag is true, the color that's set becomes the default color for the screen; it's the color that will be shown the next time the machine is booted. If the flag is false, the color is set only for the current session.

The "Background Images" section tells you how to convince the desktop to display a bitmap image.

Typically, users choose the desktop color with the Screen preferences application.

SetDPMS() , DPMSState() , DPMSCapabilities()

	status_t SetDPMS(uint32 dpmsState) uint32 DPMSState(void) uint32 DPMSCapabilities(void)

SetDPMS() lets you set the VESA Display Power Management Signaling state for the screen. The state can be one of the following values:

Constant	Meaning
B_DPMS_ON	Image is visible, normal screen operation.
B_DPMS_STAND_BY	Image is not visible, but can be restored "instantly." Saves around 30% of the power used by the monitor in B_DPMS_ON mode.
B_DPMS_SUSPEND	Image is not visible, but can be restored in less than five seconds. Saves more power by turning off the CRT's heater. The amount of savings (or if there's any) depends on the display.
B_DPMS_OFF	Image is not visible and will take some time to restore. Typically turns off all monitor power except the processor watching the sync signals for a higher power state (typically B_DPMS_ON).

DPMSState() returns the current display state, indicating whether the monitor is on or off or in one of the two sleep modes.

DPMSCapabilities() indicates which of the above modes the monitor supports.

SetMode() see GetModeList()

SetToNext

	status_t SetToNext(void)

In the current BeOS release, this function always returns B_ERROR.

WaitForRetrace()

	status_t WaitForRetrace(void) status_t WaitForRetrace(bigtime_t timeout)

Blocks until the monitor has finished the current vertical retrace, then returns B_OK. There are a few milliseconds available before it begins another retrace. Drawing changes made to the frame buffer in this period won't cause any "flicker" on-screen.

For some graphics card drivers, this function will wait for vertical sync; for others it will wait until vertical blank, providing a few extra milliseconds.

The timeout argument lets you provide a timeout in microseconds—if the screen hasn't retraced within the limit, the function returns B_ERROR.